home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 1995 #1 / Amiga Plus 1995 #1.iso / fish-disketten / fish_941-950 / d946 / priman / priman.doc < prev    next >
Text File  |  1994-12-13  |  13KB  |  285 lines
  1.                                    PriMan
  2.  
  3.                            A task priority manager
  4.                     Requires Amiga Release 2 (or greater)
  5.  
  6.                        Copyright 1993 Barry McConnell
  7.  
  8.  
  9. Distribution:
  10. ~~~~~~~~~~~~~
  11.  
  12. This program is Freeware.  You may freely distribute it, and charge only a
  13. small fee to cover expenses.  It must remain unmodified, and accompanied by
  14. this doc file (and optionally the source code).
  15.  
  16. Fred Fish is explicitly given permission to place this program on his fine
  17. disk collection.  Walnut Creek are also allowed to use it on their Aminet
  18. CD-ROM.
  19.  
  20. If you like PriMan, or have any bug reports or suggestions, please send me a
  21. message via e-mail (or a postcard, if you don't have access to Internet or
  22. FidoNet).
  23.  
  24. As with any free software, you use PriMan entirely at your own risk.  If you
  25. manage to start off World War 3 by discovering a bug, then I can not be held
  26. responsible...
  27.  
  28.  
  29. Overview:
  30. ~~~~~~~~~
  31.  
  32. PriMan is a fully Style Guide-compliant program for viewing a list of all
  33. running tasks, and performing some actions on them.  The window in which the
  34. list appears can be resized, the fonts used can be chosen from a settings
  35. window, and customised settings can be stored in the ToolTypes.  PriMan takes
  36. advantage of a few extra features available under Release 3, although you
  37. probably won't notice these unless you examine the source code carefully. :-)
  38.  
  39. PriMan allows the user to change the priority of any task with the greatest
  40. of ease.  Unlike most other utilities, you need only drag a slider to change
  41. the priority -- there is no messy clicking in string gadgets, deleting the
  42. old priority, and typing in a new one.  Also, there are buttons to signal a
  43. task with Ctrl-C, and remove it from memory.  Optionally, an "Are you
  44. sure?"-style requester can prevent you from doing this accidentally.  And if
  45. you like to have it handy all the time, there is an Iconify option, as well
  46. as the ability to leave it running in the background all the time as a
  47. Commodity.
  48.  
  49.  
  50. Using PriMan:
  51. ~~~~~~~~~~~~~
  52.  
  53. Main Window:
  54.  
  55. - ListView gadget.  This is where all the tasks are displayed, with their
  56. priority in the second column.
  57.  
  58. - Slider gadget.  Drag this and let go to change the currently-selected
  59. task's priority.  Alternatively, click to the left or right of the bar to
  60. change the priority in steps of one.
  61.  
  62. - Break button.  This will signal the task with "Ctrl-C".  Many programs
  63. abort if they receive this signal.  It is a nice way of letting something
  64. know you want it to finish, as it gives it a chance to clean up after itself.
  65. PriMan will wait for half a second after sending the signal, to give the task
  66. a chance to exit, before updating the ListView.
  67.  
  68. - Kill button.  This is nastier than the Break gadget, as it doesn't give the
  69. task a say in the matter.  It just removes it from memory, meaning any memory
  70. regions may not be freed up, resources will not be available to other tasks,
  71. etc.  This button should really only be used as a last resort for tasks that
  72. have gone out of control.
  73.  
  74. Note that removing a task that has exited since PriMan's display was last
  75. updated is NOT a good idea!  PriMan does some simple checking to ensure you
  76. don't do this, but it is not 100% foolproof. (98.8%, actually. :-)  If your
  77. Amiga crashes because you told PriMan to remove a non-existent task, you have
  78. nobody to blame but yourself...
  79.  
  80. If the task has any windows open, PriMan will ask you if you want to close
  81. them as well.  Likewise, it is not a good idea to answer "yes" to this
  82. question if, since putting up the requester, the windows have already been
  83. closed.  Your Amiga will certainly crash if you do this.
  84.  
  85. - Settings button.  This will open up the settings window, described below.
  86.  
  87. - Size gadget (lower right border of window).  You can make the window small
  88. enough to accommodate only two tasks in the ListView, or large enough to fill
  89. the screen.  All the gadgets in the window will be redrawn to fit in with the
  90. new window size.
  91.  
  92. There are also a few keys you can press:
  93.  
  94. The Help key brings up some information about me, and the version number.
  95.  
  96. The Space and Return keys both update the ListView.  Note that this operation
  97. is very expensive, as it must disable task switching and interrupts, before
  98. walking through both of Exec's task lists, making a copy of each entry, and
  99. sorting them into alphabetical order.  Thus you may get a serial error if you
  100. are doing a modem transfer, or the pointer may "flash" if you are using
  101. LacePointer on a slow Amiga.
  102.  
  103. The Tab key alternates between "narrow" and "wide" scales for the slider
  104. gadget, if it is not disabled.  Normally, the slider displays task priorities
  105. between -25 and +25, as it is unusual to find a task with an extremely low or
  106. extremely high priority.  By pressing Tab, a "wide" scale can be used,
  107. allowing you to move the slider outside the -25 to +25 range.  This operation
  108. is done automatically if you select a task that happens to have a priority
  109. outside this range.
  110.  
  111. The Escape key is similar to clicking the close gadget.  However, if you
  112. have enabled the Iconify option (see below) or are running PriMan as a
  113. Commodity, this will force it to quit, instead of closing down its windows
  114. and running in the background.
  115.  
  116.  
  117. Settings Window:
  118.  
  119. - "Gadget Font..."  This will bring up the standard ASL Font requester, where
  120. you can select the font used for all the buttons.
  121.  
  122. - "List Font..."  A different (non-proportional) font needs to be used for
  123. the ListView, as otherwise the second column would not line up properly. 
  124. This is where you select it.
  125.  
  126. - "Confirm actions"  If you are afraid of accidentally signalling or
  127. removing a task, select this checkbox.  PriMan will then ask you for
  128. confirmation before performing either of these actions.
  129.  
  130. - "Iconify when closed"  If this is selected, whenever you click the close
  131. gadget on the main window, an AppIcon will be placed on the Workbench.
  132. Double-clicking on this will open the main PriMan window again.
  133.  
  134. - "Install as a Commodity"  Should you not want PriMan to be a Commodity,
  135. you can deselect this checkbox.  Note that when you click the "Save" or "Use"
  136. buttons (see below), PriMan will install or remove itself as a Commodity,
  137. depending on this setting.  If it tries to install itself, and finds another
  138. copy of PriMan already installed, it will quietly exit, and the first copy
  139. will bring itself to the front.
  140.  
  141. - "Popup when launched"  If you are putting PriMan into your WBStartup
  142. drawer, you may like to have this option deselected, so it will be silently
  143. started each time you boot your Amiga.  Note that this option is ignored if
  144. you don't have one (or both) of "Iconify when closed" and "Install as a
  145. Commodity" selected, as otherwise there would be no way of letting PriMan
  146. know when you want it to open its window!
  147.  
  148. - "Hotkey"  If you have PriMan running as a Commodity, this is the keypress
  149. you use to open its window.  Check out your Workbench manual to find out
  150. the acceptable combinations of keypresses.
  151.  
  152. - "Priority"  This is the Commodity priority PriMan runs at.  It is best
  153. left at zero, and only really comes into play when two commodities try to
  154. allocate the same hotkey for themselves.  Note that this setting is only read
  155. once: when you first launch PriMan.  Any change you make to it will not get
  156. recognised until you quit PriMan and launch it again.  (This is not really a
  157. problem, since in practice you will always leave it at zero.)
  158.  
  159. - Save button.  This will write out your font choices, confirmation setting,
  160. and window size and position to PriMan's ToolTypes, held in the PriMan.info
  161. file (choose "Get Info" from Workbench if you need to change these manually).
  162. Any ToolTypes already present that PriMan does not recognise will be
  163. preserved. Valid ToolTypes include:
  164.  
  165.   LEFT      = left edge of window
  166.   TOP       = top edge of window
  167.   WIDTH     = window width
  168.   HEIGHT    = window height
  169.   GADFONT   = name of font used for gadgets
  170.   GADSIZE   = height of GADFONT
  171.   LISTFONT  = name of (non-proportional) font used in the ListView
  172.   LISTSIZE  = height of LISTFONT
  173.   ICONLEFT  = left position of AppIcon
  174.   ICONTOP   = top position of AppIcon
  175.   CONFIRM   = YES|NO - the "Confirm actions" setting
  176.   ICONIFY   = YES|NO - the "Iconfiy when closed" setting
  177.   COMMODITY = YES|NO - the "Install as a Commodity" setting
  178.  
  179. The standard Commodity ToolTypes also apply:
  180.  
  181.   CX_POPUP    = YES|NO - open window when first launched?
  182.   CX_POPKEY   = keypresses to open PriMan's window (or bring it to the front)
  183.   CX_PRIORITY = Commodity priority (best left at 0)
  184.  
  185. PriMan's internal defaults will be used for any ToolTypes that are missing. 
  186. If you don't specify both a name and a height for either of the fonts, then
  187. PriMan will use your Workbench Preferences settings for that font.
  188.  
  189. When running from the Shell, the settings are taken from the command-line
  190. instead.  Hence the "Save" gadget will be ghosted, as the ToolTypes will
  191. never be accessed from the Shell.  Also, you won't be able to iconify
  192. PriMan.
  193.  
  194. - Use button.  PriMan will use these settings, but not write them out to
  195. disk.  Like the Save button, the main window will be redrawn if you chose a
  196. new font.
  197.  
  198. - Cancel button.  Go back to the main window without making any changes.  The
  199. close gadget on the window also performs this function.
  200.  
  201.  
  202. Future additions:
  203. ~~~~~~~~~~~~~~~~~
  204.  
  205. - Keyboard shortcuts for all the gadgets.
  206.  
  207. - AmigaGuide documentation (and online help...).
  208.  
  209. Oh, and sorry about the icon -- I'm a programmer, not an artist! :^)  My
  210. colour scheme is also probably completely different to yours.  Prettier icons
  211. will be gratefully accepted...
  212.  
  213.  
  214. History:
  215. ~~~~~~~~
  216.  
  217. v1.1  Now complains if you try to "Break" or "Kill" it (obviously!).
  218.  
  219.       Walks through Intuition's list of screens and windows when removing a
  220.       task.  If it finds any open windows belonging to that task, it asks you
  221.       if you want to close them as well.  Currently doesn't close screens,
  222.       because that is even more dangerous. :-)
  223.  
  224.       Moved around the code for building the task list, taking almost
  225.       everything out of the Disable() ... Enable() section.  Now it just
  226.       generates an array of pointers to the tasks when interrupts are
  227.       disabled, and does the actual sorting later on.  This means your
  228.       pointer is less likely to flash if you are using LacePointer, and
  229.       serial I/O will be not be affected as badly.  Thanks to David Swasbrook
  230.       for giving me the incentive to do this.
  231.  
  232.       Added in error messages if PriMan has to suddenly abort for any
  233.       reason.  If you are _really_ low on memory, you may not get them...
  234.  
  235.       The Settings window is now the same width as the main window, so PriMan
  236.       no longer has to look at the width of the Gadget font when trying to
  237.       fit a decent number of characters into the font boxes.  Thanks to James
  238.       Young for spotting that PriMan did not work well with the Junod 8 point
  239.       font (from the AmigaGuide archive).  The font structure appears to be
  240.       flawed, and reports that it can be a maximum of 258 pixels wide...
  241.  
  242.       Fixed bug where you could still resize the main window when the "About"
  243.       requester was open.
  244.  
  245.       Major changes to code means PriMan is now more multithreaded.  You can
  246.       have the Settings window (but not any system requesters) open, and
  247.       still play around with the main window.
  248.  
  249.       Added an AppIcon feature, which can be turned on from the Settings
  250.       window.  If enabled, closing the main window will place an AppIcon on
  251.       the Workbench screen, and double-clicking that will open the main
  252.       window again.  To leave PriMan for good, press Escape.
  253.  
  254.       PriMan now accepts arguments from the Shell.
  255.  
  256.       Added a Commodity interface.  PriMan does everything you would expect
  257.       when you play around with the Commodities Exchange program.  If you try
  258.       launching PriMan twice, the original one will be de-iconified (if
  259.       necessary) and then brought to the front.  The enable/disable buttons
  260.       in Exchange do nothing to PriMan.  Pressing Escape in PriMan also
  261.       removes it for good (like when using the Iconify option).
  262.  
  263. v1.0  Initial release
  264.  
  265.  
  266. Thanks:
  267. ~~~~~~~
  268.  
  269. ...go to Eddy Carroll, for testing, suggestions, and being kind enough to run
  270. Enforcer for me until I got my A3000. :-)  Also thanks to everyone else who
  271. gave me feedback and ideas.
  272.  
  273.  
  274. Contacting me:
  275. ~~~~~~~~~~~~~~
  276.  
  277. Snail mail:  Barry McConnell,
  278.              "Piper's Hollow",
  279.              Hillcrest Road,
  280.              Dublin 18,
  281.              Ireland.
  282.  
  283. Internet:    bmccnnll@unix1.tcd.ie
  284. FidoNet:     2:263/150.2
  285.